feat: simplify agent booking flow — pre-resolution, tool filtering, Redis persistence

Summary

Six phases of changes to the AI agent's booking flow:

Phase 1: Smart @mention booking flow with multi-attendee support

Upgrades the booking flow so @Cal.com book a meeting with @bailey and @Keith Williams works end-to-end on Slack and Telegram — with clarification-first logic, multi-attendee resolution, and a fast-path for fully-specified requests.

Tool & API changes (lib/agent.ts, lib/calcom/client.ts, lib/calcom/types.ts):

• book_meeting — adds optional guestEmails: string[] field, passed as guests in the POST /v2/bookings payload (Strategy A: email-only additional attendees)
• add_booking_attendee (new) — calls POST /v2/bookings/{uid}/attendees to add a full attendee record after booking (Strategy B: resolved Slack @mentions with name + timezone)
• CreateBookingInput — adds guests?: string[]
• AddAttendeeInput (new type) + addBookingAttendee() client function

Phase 2: Architectural simplification (inspired by Gemini CLI patterns)

Eliminates unnecessary tool calls by moving auth checks and user resolution out of the AI layer, persisting tool results across turns, and adding context-aware tool filtering.

Changes in lib/agent.ts:

• Removed check_account_linked tool — bot.ts already calls getLinkedUser() before invoking the agent; every tool's execute already checks getAccessTokenOrNull(). Redundant AI-decided call eliminated.
• Injected user context into system prompt — new UserContext interface (email, username, timezone) passed from bot layer. Eliminates need for AI to call get_my_profile for basic info.
• Rewrote system prompt — replaced 5-step prescriptive booking choreography with a checklist-based framework: 4 required pieces of info (attendee, event type, date/time, availability), clear decision logic for when to book vs. ask, references to pre-resolved context blocks.
• Context-aware tool filtering — tools split into CORE (8 booking tools: list_event_types, list_event_types_by_username, check_availability, book_meeting, add_booking_attendee, list_bookings, get_booking, cancel_booking) and EXTENDED (admin tools like schedule/event type management, profile, etc.). Intent detector selects which set based on message keywords. lookup_platform_user and get_my_profile moved to EXTENDED.
• Loop guard — prepareStep callback tracks tool calls across steps; forces text response if same tool called with identical arguments (threshold: 2).
• MAX_STEPS reduced 15 → 6 — with pre-resolution, context injection, and tighter loop guard, agent should need 3-4 steps max.

Changes in lib/bot.ts:

• preResolveMentions() — before calling agent, extracts all <@USER_ID> patterns, resolves them via Slack API in parallel, returns { text, attendees }. The text has a [Context: @mentions resolved] block prepended; the attendees array is persisted to Redis for cross-turn reuse.
• buildUserContext() — converts linked user data to UserContext for system prompt injection.
• persistBookingContext() — detects ASAP intent via regex, persists _booking_intent and _resolved_attendees as tool context entries in Redis so they appear in [CACHED TOOL DATA] on subsequent turns.
• buildEnrichedMessage() — reads tool results from Redis, deduplicates by tool name (keeping latest), and prepends [CACHED TOOL DATA] directly into the user message so the model treats it as part of the current request.
• postAgentStream() tool persistence — after each agent run, extracts tool results from the stream's steps and writes them to Redis (merged with existing, capped at 10 entries).
• Slack mention reconstruction — reconstructSlackMentions() + normalizeSlackText() used in onNewMention and onSubscribedMessage handlers.
• All three handlers (Telegram freeform, onNewMention, onSubscribedMessage) updated to build userContext, enrich messages with cached data, detect tool set, and pre-resolve mentions.

Changes in lib/user-linking.ts:

• ToolContextEntry interface + getToolContext() / setToolContext() — Redis-backed tool result persistence keyed by calcom:tool_context:{threadId} with 30-minute TTL.

Phase 3: Booking flow bug fixes (log-informed)

Fixes tool call looping, "in the past" hallucination, ASAP handling, and reduces round-trips — root causes identified from server logs of real conversations.

Changes in lib/agent.ts:

• Timezone-aware date injection — system prompt now shows both UTC and user-local time (e.g. Current date/time (your timezone, Asia/Kolkata): Thursday, March 13, 2026, 6:49 PM IST). Adds explicit rule: "A date is 'in the past' ONLY if it has already passed in the user's timezone." Eliminates the hallucinated "in the past" error caused by UTC-only timestamps.
• Loop guard tightened — threshold lowered from 3 → 2 identical calls. The model was wasting 6+ steps re-calling list_event_types before the guard fired.
• MAX_STEPS reduced 8 → 6 — a well-functioning booking flow needs at most 4 steps (list_event_types → check_availability → book_meeting → text).
• ASAP/urgency handling — new prompt section for "ASAP", "as soon as possible", "earliest", "next available" — auto-fetches availability for next 3 days instead of asking "what date/time?". Cross-turn persistence via _booking_intent in Redis means follow-up messages ("use the 15 min one") honor the original ASAP intent.
• Duration mismatch detection — flags conflicts between user's specified time range and event type duration (e.g. "10:00-10:15 AM" for a 30-min event).
• Single event type auto-select — if only 1 non-hidden event type exists, auto-selects it instead of asking.
• Strengthened tool rules — "NEVER call the same tool more than once in a single step", "If check_availability returns slots, USE them" (model was discarding results and asking for a date).
• check_availability zero-slots handling — when no slots found in the requested range, auto-searches next 14 days for alternatives. Returns structured { totalSlots: 0, noSlotsReason, nextAvailableSlots } with weekend detection and clear instructions to the model.
• .passthrough() on empty zod schemas — prevents tool call rejections when LLM sends unexpected extra properties in args for no-parameter tools.
• Expanded isAIToolCallError — catches "tool call validation failed" and "which was not in request.tools" (relevant with CORE/EXTENDED tool filtering).

Changes in lib/bot.ts:

• withSlackToken() helper — wraps async operations with Slack bot token explicitly set in context, preventing not_authed errors when AsyncLocalStorage context is lost across async boundaries (Vercel waitUntil, long-running agent streams).
• promptUserToLink() helper — extracted duplicated OAuth link prompt logic from onNewMention and onSubscribedMessage into single reusable function. Supports "expired" reason with different card title.
• Token expiry checks — all 3 handlers now call getValidAccessToken() after getLinkedUser() and show "session expired" card if token is revoked.
• safePost wrappers — error posting in onNewMention and onSubscribedMessage wrapped with withSlackToken to prevent auth context loss.

Phase 4: Attendee calendar booking flow

Adds a "book on attendee's calendar" option. When a user mentions someone and wants to book, the bot can now ask whose event types to use — the host's (current behavior) or the attendee's (new). If the attendee's, their public Cal.com event types are fetched by username.

Changes in lib/calcom/client.ts:

• getEventTypesByUsername() (new) — calls GET /v2/event-types?username=<username> with only the cal-api-version: 2024-06-14 header (no auth token required). Returns the same CalcomEventType[] shape as the authenticated getEventTypes().
• getAvailableSlotsPublic() (new) — calls GET /v2/slots with eventTypeSlug + username query params, cal-api-version: 2024-09-04. No auth required.
• createBookingPublic() (new) — unauthenticated POST /v2/bookings with eventTypeSlug + username. Enhanced error parsing from response body.

Changes in lib/agent.ts:

• list_event_types_by_username (new tool) — wraps getEventTypesByUsername(). Returns event types with id, title, slug, duration, description, hidden, bookingUrl, and bookingFields.
• check_availability_public (new tool) — wraps getAvailableSlotsPublic(). Same zero-slots handling as authenticated version.
• book_meeting_public (new tool) — wraps createBookingPublic(). Takes eventTypeSlug + username instead of eventTypeId.
• All three added to CORE_TOOL_NAMES — available in the core booking flow.
• "WHOSE CALENDAR TO USE" prompt section — STEP 0 of booking flow: asks whose event types to use. Option A (your calendar) routes through authenticated tools, Option B (their calendar) routes through public tools.
• Critical rule fix: restore expo-wxt-app scheme for Android OAuth redirect #6 — "NEVER call check_availability for another user's event type — use check_availability_public instead."

Changes in lib/calcom/types.ts:

• CreatePublicBookingInput — new type with eventTypeSlug, username, start, attendee, guests?, notes?, lengthInMinutes?.

Phase 5: Fix false-positive Slack auth error + custom booking field support

Fixes a bug where the "Slack app token has expired" error was a false positive triggered when the AI agent's streaming response fails mid-flight (e.g. due to a Cal.com API booking error for missing custom fields), and the resulting error is misclassified as a Slack auth error in the error handling chain. Also adds responses field support for custom booking fields.

Root cause: When the agent stream fails (e.g., Cal.com returns 400 for missing required booking fields), the error can cause AsyncLocalStorage context loss on Vercel's serverless runtime. Subsequent Slack API calls then fail with not_authed, which withBotErrorHandling classifies as "Slack app token has expired" — masking the real error.

Changes in lib/bot.ts:

• getCustomErrorMessage updated in all 3 handlers — now accepts the caught err parameter. When lastStreamErrorRef.current is set (meaning the agent stream had an error) and the caught error is a Slack auth error, returns a generic "Sorry, something went wrong" message instead of the misleading "token expired" message.
• postAgentStream hardened — catch block now checks if the thrown error is a Slack auth error AND the agent stream had captured errors (via onErrorRef.current). If so, re-throws as a generic Error with the original stream error message, preventing the Slack auth error from propagating to withBotErrorHandling.

Changes in lib/calcom/types.ts:

• responses?: Record<string, unknown> added to both CreateBookingInput and CreatePublicBookingInput — allows passing custom booking field values to the Cal.com API.

Changes in lib/agent.ts:

• responses parameter added to both book_meeting and book_meeting_public tool schemas (z.record(z.string(), z.unknown())), passed through to createBooking() and createBookingPublic() calls.
• bookingFields included in list_event_types_by_username tool response — the agent can now see which custom fields an event type requires.
• CUSTOM BOOKING FIELDS prompt section — instructs the agent to check for required: true booking fields, collect values from the user, and pass them as responses in the booking call.
• CRITICAL RULES renumbered — fixed duplicate rule fix: restore expo-wxt-app scheme for Android OAuth redirect #6 (was 6,6,7,8 → now 6,7,8,9).
• Lint fix — replaced 4 non-null assertions (!) with nullish coalescing (?? "") in check_availability_public to satisfy biome noNonNullAssertion rule.

Phase 6: Encrypt tool context + webhook notification routing metadata

Addresses PR review feedback: encrypts PII in Redis tool-context entries and adds metadata to booking API calls so Cal.com webhooks can route notifications back to the correct Slack/Telegram user.

Changes in lib/user-linking.ts:

• setToolContext now wraps JSON.stringify(entries) with encryptData() before writing to Redis. Tool context can contain PII (attendee names, emails from resolved mentions, booking details).
• getToolContext now wraps the raw Redis value with decryptData() before JSON.parse. Legacy plaintext entries are handled gracefully by decryptData (the "enc:" prefix check at line 33).

Changes in lib/calcom/types.ts:

• metadata?: Record<string, string> added to CreatePublicBookingInput — was already present on CreateBookingInput.

Changes in lib/agent.ts:

• platform parameter added to createCalTools() function signature, threaded from runAgentStream().
• book_meeting execute now builds and passes metadata with slack_team_id/slack_user_id (for Slack) or telegram_chat_id (for Telegram). The webhook handler at app/api/webhooks/calcom/route.ts uses these fields to route booking notifications to the correct channel/DM.
• book_meeting_public execute — same metadata logic applied.

Why this matters: Previously, bookings created via the bot never included routing metadata, so Cal.com webhooks had no way to deliver Slack notifications for those bookings (the handler checks metadata.slack_team_id at line 61-63 and skips without it). Telegram had a partial fallback via organizer email lookup, but Slack had none.

Expected impact on tool call count:

Review & Testing Checklist for Human

• Verify webhook notification routing works end-to-end: Create a booking via the bot on Slack, then check that the Cal.com webhook fires and the notification is delivered back to the correct Slack channel/DM. The metadata object (slack_team_id, slack_user_id) must match what the webhook handler at app/api/webhooks/calcom/route.ts expects. This was completely broken before — bookings created via the bot never included routing metadata.
• Test the false-positive Slack auth error fix: Trigger a booking on an event type with required custom fields. Verify the agent asks for custom field values instead of showing "Slack app token has expired". Can only be verified in a deployed Slack environment.
• Verify bookingFields shape from public API: The list_event_types_by_username tool now returns bookingFields. Verify that the public GET /v2/event-types?username= endpoint returns bookingFields with name, type, and required properties as the prompt assumes.
• Verify responses field format accepted by Cal.com API: The responses object uses the field's name (slug) as the key. Confirm POST /v2/bookings expects slug-keyed responses (some APIs use id instead).
• Test the exact failing scenario from logs: "book my meeting with @dhairyashil as soon as possible" → "use this one '30 min meeting'" → "14 march 2026, 10 to 10:15 AM IST". Verify: (1) no list_event_types looping on turn 1, (2) turn 2 uses cached event types and honors ASAP intent, (3) turn 3 doesn't hallucinate "in the past".
• Test attendee calendar flow with custom fields: Book on someone's calendar whose event type has required custom fields. Verify the agent collects fields and passes them as responses in book_meeting_public.
• Verify tool-context encryption rollover: Existing unencrypted tool-context entries in Redis should still be readable after deploy (the decryptData function returns plaintext as-is when there's no enc: prefix). New entries should be encrypted.
• Verify POST /v2/bookings/{uid}/attendees endpoint exists in the Cal.com v2 API and accepts { name, email, timeZone }.
• Test token expiry flow: With an expired/revoked Cal.com token, verify the "Your Cal.com Session Has Expired" card appears (not a cryptic error).

Recommended test plan

1. Deploy to staging (Vercel preview)
2. In Slack, book a meeting via the bot → verify the booking webhook delivers a notification back to the Slack channel (this confirms metadata routing works)
3. Book on an event type with required custom booking fields → verify the agent collects values and books successfully
4. Intentionally trigger a booking error (e.g., omit a required field manually) → verify the error message is NOT "Slack app token has expired"
5. Run the exact 3-turn conversation from the bug report logs
6. Check server logs for tool call count per step — expect ≤2 steps per turn
7. Test edge cases: ASAP booking, duration mismatch, multi-attendee, expired token, attendee calendar booking with custom fields

Notes

• All pre-existing type errors in the repo (missing ai/chat/zod module declarations when not installed) are unchanged. No new type errors introduced — CI typecheck passes.
• The tool result persistence in postAgentStream() uses Record<string, unknown> casts to extract from the AI SDK's unknown[] steps type. This is intentional to avoid coupling to the SDK's complex generic StepResult type, with runtime guards (typeof r.toolName === "string") for safety.
• The check_account_linked tool removal is safe because bot.ts already gates on getLinkedUser() in all three handlers before invoking the agent. But if any new entry point is added that skips this check, there's no fallback.
• The buildEnrichedMessage approach (prepending [CACHED TOOL DATA] directly into the user message text) is a deliberate change from the earlier injectToolContext approach (injecting as a separate message in conversation history). The earlier approach was being ignored by the model. This approach makes it impossible to ignore but means the cached data is part of the "user said" content, which could have unexpected effects on model behavior.
• The getEventTypesByUsername() function makes an unauthenticated API call. There is no rate limiting or caching implemented — if the model calls it repeatedly (e.g., due to a prompt misunderstanding), it could hit Cal.com's public API rate limits.
• The postAgentStream hardening (Fix 3) depends on timing: onErrorRef.current must be set by the agent stream error handler before the Slack not_authed error is thrown. In practice this should always hold because the stream error fires first and the Slack error is a consequence, but this is worth monitoring in logs.
• Both book_meeting and book_meeting_public now always pass a metadata object (empty {} for unknown platforms). If Cal.com treats empty metadata differently from absent metadata, this could have side effects — worth verifying.
• No automated tests added — the companion repo doesn't have an agent test suite.

Link to Devin Session: https://app.devin.ai/sessions/f69e6c70ee544da7b5b6e91a9b73d29b
Requested by: @dhairyashiil